Combiner XML attachment
Combining Letters is a process of sending multiple Letters in the same envelope. This reduces postage costs.
Important!! Read this!!
The combiner XML attachment does not combine letters.
It makes letters eligible for combining.
An Eligible letter is one that has been assigned a Hash value
Letters with identical Hash values can be combined.
Letter combining takes place when an output queue is released
Creating the Hash value
A letter's Hash value is computed by combining together various parameters of the letter into a secure value (the Hash), which is appended to the letter record. Typically this would be the recipient name, address and postcode, but other attributes of the letter and text scanned from the pages can be used instead, or in addition. Other suitable letter properties to include in the Hash might be an account number scanned off the page, or a reference number.
N.B. The ID of the Server and of the Organisation sending the Letters is always included in the Hash, so Letters from different Organisations and/or different servers are never combined, even if they are to the same recipient.
Schema
<mkzAttachment type="combiner">
<onSubmit>
<combineAddress/> | <combineRecipient/>
<combinePostcode/>
<combineSSC/>
<combineDPS/>
<combineField scan|identifier />
<topmost scan|identifier contains="text" />
<onSubmit>
</mkzAttachment>
The XML can be executed during the OnSubmit phase.
The XML supports the following elements. There can be multiple instances of any of these.
<combineAddress/> or <combineRecipient/> Add either the full address or just the recipient name to the Hash.
These two elements are effectively mutually exclusive. When creating the Hash from either the Recipient Name or the full Recipient Address, HybridMail first converts the text to lower-case and ignores whitespace, full-stops and commas. For example, both the following ‘exact’ address texts create the same Hash and the two Letters would be eligible for combining.
Mr F Bloggs 2 Acacia Avenue Taunton TA1 1JJ
Mr. F. Bloggs 2, acacia avenue, Taunton, TA1 1JJ
If you choose <combineRecipient> it is essential you also include other information, such as Postcode, SSC and DPS.
<combinePostcode/> Add the postcode to the Hash.
This element should really be considered mandatory as a way of preventing accidental combines when instances of the <combineField> element are being used as the primary way to create the Hash.
<combineSSC/> and <combineDPS> Add the Standard Selection Code/Delivery Point Suffix to the Hash.
These elements should really be considered mandatory as a way of preventing accidental combines when instances of the <combineField> element are being used as the primary way to create the Hash.
<combineField scan|identifier /> Add scanned text or an identifier value to the Hash.
This element adds the text, either scanned or from an identifier, to the Hash. Multiple instances of this element may appear, in which case the text from each instance is concatenated before being added to the Hash.
<topmost scan|identifier contains="compare-text" /> Select this letter to be visible through the envelope window.
This element examines the text, either scanned or from an identifier, to see if it contains the value specified by compare-text. If so, then the letter will be presented as the topmost letter in the envelope, i.e. the one visible through the envelope window. This element does not affect the Hash.
Only one of the Letters to be combined should have matching topmost text. If more than one Letter matches, then one of those Letters will be topmost, but exactly which one is undefined. If no Letters have matching topmost text, then the topmost letter is undefined.
Notes
Letters are only combined within a single Output queue, and only up to the maximum number of sheets that will fit into the Envelope defined for that queue. Combined letters that will not fit in the Envelope are “bumped” up to the Output queue which has the “next biggest envelope”.
It is always better to over-specify a combine (many combine elements), rather than under-specify it (few combine elements). If you over-specify, the worst that can happen is that the recipient will get separate letters instead of a combined one. If you under-specify, there is a risk that a recipient will receive their letter combined with one for another person!
Examples
Combine any letters to the same recipient, but only if the account numbers are the same. I.e. if the recipient has two accounts, he will always get separate letters for each account. Ensure any final demands are visible through the envelope window.
<mkzAttachment type="combiner">
<onSubmit>
<combineAddress/>
<combinePostcode/>
<combineSSC/>
<!-- only combine with letters relating to the same account -->
<setIdentifier name="accNum" scan="10, 100, 100, 40" extract="Account:"/>
<combineField identifier="accNum" />
<topmost scan="10, 10, 40, 40" contains="Final Demand" />
<onSubmit>
</mkzAttachment>